vfile

What is vfile?

The vfile npm package is a virtual file format for text processing systems, which allows for the manipulation and handling of file-related information in a structured and consistent way. It is commonly used in projects involving the processing of markdown, text, and similar content, providing a standardized interface for plugins and utilities.

What are vfile's main functionalities?

Creating and modifying virtual files

This feature allows users to create a new virtual file and modify its contents. The example demonstrates creating a vfile with initial content and then appending additional text to it.

const vfile = require('vfile');

const file = vfile({path: './example.txt', contents: 'Hello, world!'});
file.contents += ' Modified content.';
console.log(file.contents);

Accessing file metadata

This feature enables users to access metadata of the file such as the path and basename. The example shows how to create a vfile and retrieve its path and basename properties.

const vfile = require('vfile');

const file = vfile({path: './example.txt', contents: 'Hello, world!'});
console.log(file.path); // Outputs: './example.txt'
console.log(file.basename); // Outputs: 'example.txt'

Handling errors and messages

This feature is useful for adding error or warning messages to a file, which can be particularly helpful in linting tools or compilers. The example demonstrates adding an error message to a vfile and logging all associated messages.

const vfile = require('vfile');

const file = vfile();
file.message('Unknown error', {line: 1, column: 1});
console.log(file.messages);

Other packages similar to vfile

vinyl

Vinyl is a virtual file format that is often used in the gulp build system. It is similar to vfile in that it represents file objects in a virtual form, but it is more focused on being used with streams, particularly in the context of gulp's pipelines.

mem-fs

mem-fs provides an in-memory file system which stores file representations similar to vfile. While vfile is designed for text processing with a focus on linting and transformation, mem-fs is geared more towards temporary storage and manipulation of files in memory during tasks like scaffolding or testing.

README

VFile is a virtual file format used by retext (natural language) and remark (markdown). Two processors which parse, transform, and compile text. Both need a virtual representation of files and a place to store metadata and messages. And, they work in the browser. VFile provides these requirements.

Also, VFile exposes a warning mechanism compatible with ESLints formatters, making it easy to expose stylish warnings, or export tap compliant messages.

VFile is different from (the excellent :+1:) vinyl in that it does not include file-system or node-only functionality. No buffers, streams, or stats. In addition, the focus on metadata and messages are useful when processing a file through a middleware pipeline.

Installation

npm:

npm install vfile

VFile is also available for duo, and as an AMD, CommonJS, and globals module, uncompressed and compressed.

Table of Contents

• Usage

• Related Tools

• API

  • VFile()
  • VFile#contents
  • VFile#directory
  • VFile#filename
  • VFile#extension
  • VFile#basename()
  • VFile#quiet
  • VFile#messages
  • VFile#history
  • VFile#toString()
  • VFile#filePath()
  • VFile#move(options)
  • VFile#namespace(key)
  • VFile#message(reason[, position[, ruleId]])
  • VFile#warn(reason[, position[, ruleId]])
  • VFile#fail(reason[, position[, ruleId]])
  • VFile#hasFailed()
  • VFileMessage

• License

Usage

var VFile = require('vfile');

var file = new VFile({
  'directory': '~',
  'filename': 'example',
  'extension': 'txt',
  'contents': 'Foo *bar* baz'
});

file.toString(); // 'Foo *bar* baz'
file.filePath(); // '~/example.txt'

file.move({'extension': 'md'});
file.filePath(); // '~/example.md'

file.warn('Something went wrong', {'line': 1, 'column': 3});
// { [~/example.md:1:3: Something went wrong]
//   name: '~/example.md:1:3',
//   file: '~/example.md',
//   reason: 'Something went wrong',
//   line: 1,
//   column: 3,
//   fatal: false }

Related Tools

VFiles are used by both retext and remark.

In addition, here’s a list of useful tools:

• dustinspecker/convert-vinyl-to-vfile — Convert a Vinyl file to a VFile;

• shinnn/is-vfile-message — Check if a value is a VFileMessage object;

• wooorm/to-vfile — Create a virtual file from a file-path;

• wooorm/vfile-find-down — Find one or more files by searching the file system downwards;

• wooorm/vfile-find-up — Find one or more files by searching the file system upwards;

• wooorm/vfile-location — Convert between positions (line and column-based) and offsets (range-based) locations;

• shinnn/vfile-messages-to-vscode-diagnostics — Convert VFileMessages into an array of VS Code diagnostics;

• wooorm/vfile-reporter — Stylish reporter for virtual files.

• wooorm/vfile-sort — Sort virtual file messages by line/column;

API

VFile()

VFile objects make it easy to move files, to trigger warnings and errors, and to store supplementary metadata relating to files, all without accessing the file-system.

Example:

var file = new VFile({
  'directory': '~',
  'filename': 'example',
  'extension': 'txt',
  'contents': 'Foo *bar* baz'
});

file === VFile(file); // true
file === new VFile(file); // true

VFile('foo') instanceof VFile; // true

Signatures:

• file = VFile(contents|options|vFile?).

Parameters:

• contents (string) — Contents of the file;

• vFile (VFile) — Existing representation, returned without modification;

• options (Object):

  • directory (string?, default: '') — Parent directory;

  • filename (string?, default: '') — Name, without extension;

  • extension (string?, default: '') — Extension(s), without initial dot;

  • contents (string?, default: '') — Raw value.

Returns:

vFile — Instance.

Notes:

VFile exposes an interface compatible with ESLint’s formatters. For example, to expose warnings using ESLint’s compact formatter, execute the following:

var compact = require('eslint/lib/formatters/compact');
var VFile = require('vfile');

var vFile = new VFile({
    'directory': '~',
    'filename': 'hello',
    'extension': 'txt'
});

vFile.warn('Whoops, something happened!');

console.log(compact([vFile]));

Which would yield the following:

~/hello.txt: line 0, col 0, Warning - Whoops, something happened!

1 problem

VFile#contents

string — Content of file.

VFile#directory

string — Path to parent directory.

VFile#filename

string — Filename. A file-path can still be generated when no filename exists.

VFile#extension

string — Extension. A file-path can still be generated when no extension exists.

VFile#basename()

Get the filename, with extension, if applicable.

Example:

var file = new VFile({
  'directory': '~',
  'filename': 'example',
  'extension': 'txt'
});

file.basename() // example.txt

Signatures:

• string = vFile.basename().

Returns:

string— Returns the file path without a directory, if applicable. Otherwise,an empty string is returned.

VFile#quiet

boolean? — Whether an error created by VFile#fail() is returned (when truthy) or thrown (when falsey).

Ensure all messages associated with a file are handled properly when setting this to true.

VFile#messages

Array.<VFileMessage> — List of associated messages.

Notes:

VFile#message(), and in turn VFile#warn() and VFile#fail(), return Error objects that adhere to the VFileMessage schema. Its results can populate messages.

VFile#history

Array.<String> — List of file-paths the file moved between.

VFile#toString()

Get the value of the file.

Example:

var vFile = new VFile('Foo');
String(vFile); // 'Foo'

Signatures:

• string = vFile.toString().

Returns:

string — Contents.

VFile#filePath()

Get the filename, with extension and directory, if applicable.

Example:

var file = new VFile({
  'directory': '~',
  'filename': 'example',
  'extension': 'txt'
});

String(file.filePath); // ~/example.txt
file.filePath() // ~/example.txt

Signatures:

• string = vFile.filePath().

Returns:

string — If the vFile has a filename, it will be prefixed with the directory (slashed), if applicable, and suffixed with the (dotted) extension (if applicable). Otherwise, an empty string is returned.

VFile#move(options)

Move a file by passing a new directory, filename, and extension. When these are not given, the default values are kept.

Example:

var file = new VFile({
  'directory': '~',
  'filename': 'example',
  'extension': 'txt',
  'contents': 'Foo *bar* baz'
});

file.move({'directory': '/var/www'});
file.filePath(); // '/var/www/example.txt'

file.move({'extension': 'md'});
file.filePath(); // '/var/www/example.md'

Signatures:

• vFile = vFile.move(options?).

Parameters:

• options (Object):

  • directory (string, default: '') — Parent directory;

  • filename (string?, default: '') — Name, without extension;

  • extension (string, default: '') — Extension(s), without initial dot.

Returns:

vFile — Context object (chainable).

VFile#namespace(key)

Access metadata.

Example:

var file = new VFile('Foo');

file.namespace('foo').bar = 'baz';

console.log(file.namespace('foo').bar) // 'baz';

Parameters:

• key (string) — Namespace key.

Returns:

Object — Private namespace for metadata.

VFile#message(reason[, position[, ruleId]])

Create a message with reason at position. When an error is passed in as reason, copies the stack. This does not add a message to messages.

Example:

var file = new VFile();

file.message('Something went wrong');
// { [1:1: Something went wrong]
//   name: '1:1',
//   file: '',
//   reason: 'Something went wrong',
//   line: null,
//   column: null }

Signatures:

• VFileMessage = vFile.message(err|reason, node|location|position?, ruleId?).

Parameters:

• err (Error) — Original error, whose stack and message are used;

• reason (string) — Reason for message;

• node (Node) — Syntax tree object;

• location (Object) — Syntax tree location (found at node.position);

• position (Object) — Syntax tree position (found at node.position.start or node.position.end).

• ruleId (string) — Category of warning.

Returns:

VFileMessage — File-related message with location information.

VFile#warn(reason[, position[, ruleId]])

Warn. Creates a non-fatal message (see VFile#message()), and adds it to the file's messages list.

Example:

var file = new VFile();

file.warn('Something went wrong');
// { [1:1: Something went wrong]
//   name: '1:1',
//   file: '',
//   reason: 'Something went wrong',
//   line: null,
//   column: null,
//   fatal: false }

See:

• VFile#message

VFile#fail(reason[, position[, ruleId]])

Fail. Creates a fatal message (see VFile#message()), sets fatal: true, adds it to the file's messages list.

If quiet is not true, throws the error.

Example:

var file = new VFile();

file.fail('Something went wrong');
// 1:1: Something went wrong
//     at VFile.exception (vfile/index.js:296:11)
//     at VFile.fail (vfile/index.js:360:20)
//     at repl:1:6

file.quiet = true;
file.fail('Something went wrong');
// { [1:1: Something went wrong]
//   name: '1:1',
//   file: '',
//   reason: 'Something went wrong',
//   line: null,
//   column: null,
//   fatal: true }

See:

• VFile#message

VFile#hasFailed()

Check if a fatal message occurred making the file no longer processable.

Example:

var file = new VFile();
file.quiet = true;

file.hasFailed(); // false

file.fail('Something went wrong');
file.hasFailed(); // true

Signatures:

• boolean = vFile.hasFailed().

Returns:

boolean — true if at least one of file’s messages has a fatal property set to true.

VFileMessage

Error — File-related message with location information.

Properties:

• name (string) — (Starting) location of the message, preceded by its file-path when available, and joined by ':'. Used by the native Error#toString();

• file (string) — File-path;

• reason (string) — Reason for message;

• line (number?) — Line of error, when available;

• column (number?) — Column of error, when available;

• stack (string?) — Stack of message, when available;

• fatal (boolean?) — Whether the associated file is still processable.

• location (object) — Full range information, when available. Has start and end properties, both set to an object with line and column, set to number?.

License

MIT © Titus Wormer